Closes #4291
Closes #1208 ( most of it. There is still an open question about schedulers)

Blocked by:

• https://github.com/realm/realm-java/pull/6590/files#diff-4e0e1e80f7c3471fb1ff091a810a021dR140

This PR adds support for frozen Realm objects. The major benefit of frozen objects is that they are not thread confined and can thus be accessed on any thread. This is especially important for most kinds of stream-based architectures (which is most of them at this point).

The trade-off is that the objects are then immutable (which is actually considered a positive for most reactive architectures on Android)

High level API

// Adding two new methods to all top level Realm objects: .freeze() and .isFrozen()
// Anything can be frozen: Realm, Results, Lists, Objects
Realm realm = Realm.getInstance(config);
Realm frozenRealm = realm.freeze();
RealmResults<Person> persons = realm.where(Person.class).findAll().freeze();
Person p = realm.where(Person.class).findFirst().freeze();
RealmList<Child> children = realm.where(Person.class).findFirst().getChildren().freeze();

// The RxJava factory will be changed so observables now emit frozen objects by default
Realm realm = Realm.getInstance(config);
realm.where(Person.class).findAllAsync().asObservable()
  .map((result, changeSet) -> {
    result.isFrozen() == true;    
  })

// It is still possible to navigate and query a frozen Realm just like a live one, 
// but all objects will be frozen
Realm realm = Realm.getInstance(config);
Realm frozenRealm = realm.freeze();
frozenRealm.where(Person.class).findAll().isFrozen() == true;

// Because freezing objects increase the chance of leaking versions and thus 
// disk space we should expose some logic around Cores tracking of versions. 
// I suggest throwing an exception if the number of active versions goes over 
// a certain number.
RealmConfiguration config = new RealmConfiguration.Builder()
  .maxNumberOfActiveVersions(20);
  .build();

Semantics

Freezing an object will freeze the entire object graph at that version, effectively turning it read-only. Doing this will also lift the thread-confined restriction on it.

These are still to be decided, but so far I'm envisioning the following

• Starting a write transaction on a frozen Realm will throw an exception
• Trying to add a change listener will throw an exception.
• Trying to refresh a Realm in any way will throw an exception
• Trying to write to a frozen object inside the live Realms write transaction will throw.
• Doing liveRealm.copyToRealmOrUpdate(frozenObject) should work the same way as using unmanaged objects.

Open design questions

Realm.getLocalInstanceCount(config):
What are the semantics of Realm.getLocalInstanceCount(config) for frozen Realms?

For now, globalCount == LocalThreadCount for frozen Realms, since these Realms are not thread constrained.

What are the semantics if the live Realm spawning frozen Realms is closed?
There are conflicting interests in terms of making it easy to reason about a Realm files life cycle vs. the Java objects. I.e. it becomes difficult to close a Realm file if frozen objects cannot easily close their Realm.
]
I can think of two solutions: 1) When all live Realms across all thread are closed, this will also automatically close all frozen Realms or 2) Introduce something like Realm.closeFrozenRealms(config) which will do it manually. It is unclear what is better.

For now, frozen Realms will all be closed when the live Realm spawning them are. This is primarely driven by making RxJava support easier.

Freeze existing object or return frozen copy?
Should freezing objects return a frozen copy or freeze the object in place?

There are performance benefits to freezing current object, but it seems to conflict with e.g. RxJava support and people need access to the live object in order to get notifications. Kotlin Multiplatform freeze in place.

For now we return frozen copies. I suggest we leave it up to user feedback to see if we should change it. We can consider having an internal method that freezes in-place if it will improve performance a lot.

Equality and hashcode:
How should object equality work for frozen objects? Current RealmLists and RealmLists compare objects on pr. object basis. How should frozen Realms and objects be compared?

For now Frozen objects with the same values are not considered equal to a live object. Same for Realms. Frozen objects at different versions (but equal values) are also not considered equal.

Use cases are unclear. The suggestion is to leave it up to user feedback to see if we should change it.

Generic parameter on RealmModel?
So it becomes: RealmModel<MyImplementation>, e.g public class Dog extends RealmObject<Dog>.

This enables better return types on freeze() as well as the current asFlowable() (which is kinda annoying to use). Setting the parameter is optional in Java (non-breaking), but seems to be required in Kotlin if present.

Unclear if we want to break everyone using Kotlin for this, but it will remove a lot of annoying casts. I will defer changing this to a later PR so we can discuss further (and to prevent cluttering this PR too much).

Benchmark results (on Emulator)

Results where frozen with 10.000 objects. It looks like freezing TableViews are fast enough that we don't need to be too concerned about performance. For a more scalable solution we should look into freezing TableViews off the UI thread (but doing it on the notifier thread also seems like a bad idea).

benchmark:       149,500 ns EMULATOR_UNLOCKED_FrozenObjectsBenchmarks.freezeResults
benchmark:        27,400 ns EMULATOR_UNLOCKED_FrozenObjectsBenchmarks.freezeList
benchmark:        24,454 ns EMULATOR_UNLOCKED_FrozenObjectsBenchmarks.freezeObject
benchmark:        14,375 ns EMULATOR_UNLOCKED_FrozenObjectsBenchmarks.freezeRealm

TODO:

• Changelog
• Cleanup
• Finalize Add support for frozen objects realm-object-store#856 and merge it to master
• Implement RealmObject.freeze() and RealmObject.isFrozen()
• Implement RealmModel.freeze() and RealmModel.isFrozen()
• Implement RealmList.freeze() and RealmList.isFrozen()
  Implement RealmResults.freeze() and RealmResults.isFrozen()
• Implement Realm.freeze() and Realm.isFrozen()
• Implement DynamicRealm.freeze() and DynamicRealm.isFrozen()
• It should be possible to freeze deleted objects (which might seem a bit weird, but is needed for us to support event streams that want to notify about deleted objects).
• Fully closing the live Realm should also close all frozen instances
• Add benchmarks for freezing Realm
• Add benchmarks for freezing large RealmResults
• Add benchmark for freezing large RealmList
• Add benchmark for freezing RealmObject
• Javadoc
• Change RxObservableFactory so it returns frozen objects.
• Add option to RealmConfiguration to throw at certain number of active versions. Should be checked when we start a write transaction.
• All mutator methods should throw on frozen Realms
• Tests: Starting write transactions fail
• Tests: Adding Realm listeners fail
• Tests: Adding Results listeners fail
• Tests: Adding List listeners fail
• Tests: Adding Object listeners fail
• Tests: refreshing fail
• Tests: Equality of frozen Realms
• Tests: Equality of frozen RealmObject
• Tests: copyOrUpdate frozen Realm data
• Tests: insertOrUpdate frozen Realm data
• Other tests